home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Fritz: All Fritz
/
All Fritz.zip
/
All Fritz
/
FILES
/
PROGASIC
/
COMMENTS.LZH
/
COMMENTS.DOC
< prev
next >
Wrap
Text File
|
1991-04-16
|
62KB
|
1,584 lines
COMMENTS v.1.2
The QuickBASIC comments adding utility
by LAMCO Software
User's manual
Copyright (c) 1991 - LAMCO Software
In U.S.A., In Canada,
P.O. Box 847 P.O. Box 46
St-Albans Postal Station P.A.T.
VT Montreal, Quebec
05478 H1B 5K1
┌┬──────────────────────────────────────────────────────────────────────┬┐
││ COMMENTS - Version 1.2 ││
││ ││
││ (c) 1991 by LAMCO Software ││
││ ││
││ The program that will add comments for ││
││ you in any of your QuickBASIC listings ││
└┴──────────────────────────────────────────────────────────────────────┴┘
┌┬────────────────────────────────────────────────────────────────┬┐
││ QuickBASIC is a registered trademark of Microsoft Corp. Inc. ││
└┴────────────────────────────────────────────────────────────────┴┘
┌┬──────────────────────────────────────────────────────────────────────┬┐
││ Contents ││
└┴──────────────────────────────────────────────────────────────────────┴┘
1 - What is COMMENTS . . . . . . . . . . . . . . . . . . . . . 3
2 - What is added to the module level of your listing . . . . 4
3 - What is added to each procedure of your listing . . . . . 5
4 - Requirements . . . . . . . . . . . . . . . . . . . . . . . 6
5 - How COMMENTS works . . . . . . . . . . . . . . . . . . . . 8
6 - About '$INCLUDE files and .MAK files . . . . . . . . . . . 9
7 - How to use COMMENTS . . . . . . . . . . . . . . . . . . . 9
8 - How to use COMMENTS - Systems without a hard drive . . . . 10
9 - How to use COMMENTS - Answering prompts . . . . . . . . . 11
10 - COMMENTS Limitations . . . . . . . . . . . . . . . . . . . 22
11 - Technical support . . . . . . . . . . . . . . . . . . . . 23
12 - What's coming up in version 2.0 . . . . . . . . . . . . . 23
13 - About Shareware (Registration) . . . . . . . . . . . . . . 24
┌┬──────────────────────────────────────────────────────────────────────┬┐
││ 1 - What is COMMENTS ││
└┴──────────────────────────────────────────────────────────────────────┴┘
Any serious reference manual about programming in any language says at
least once that every programmer should use comments extensively.
Let's face it, that's the part of writting a program that everybody hates
the most.
COMMENTS takes care of a great part of that burden for you by adding to
your listing all the information it can gather from analyzing it.
COMMENTS makes a backup copy of your listing in a file that uses the same
filename with a .BAK extension.
It also creates a separate file with a .STR extension that will contain
the complete structure of your listing if there is at least one procedure.
The new file with a .BAS extension will contain your listing and the
following :
In the Main Module section : For each procedure :
- Name and type - Name and type
- Name of the module (file) - Description
- Language used - Parameters
- Source of the program - All the variables used
- Description - Module level declarations
- Requirements - CONST statements
- Command line parameters - TYPE structures
- Files listed in .MAK file - DECLARE FUNCTION
- All the variables used - DECLARE SUB
COMMENTS doesn't modify your listing in any way. Everything that is added
to your listing by COMMENTS is written inside a box that is added at the
very beginning of the file or over the first line of a procedure (SUB or
FUNCTION).
COMMENTS will adjust automatically for color or monochrome monitors.
COMMENTS v.1.2 - by LAMCO Software Page 3
┌┬──────────────────────────────────────────────────────────────────────┬┐
││ 2 - What is added to the module level of your listing ││
└┴──────────────────────────────────────────────────────────────────────┴┘
There is one box for each kind of information that COMMENTS can gather
from your listing. The boxes added to the module level will be :
2.1 - The MAIN box that will contain the Name, Type, Module name,
Language, and Source of your listing.
2.2 - The DESCRIPTION box contains the description of your program. You
must of course type in that description.
2.3 - The REQUIREMENTS box. This box will list all that is required by
your program to work properly, that may be for example a CGA or
VGA monitor, or a special Quick Library, or a particular version
of DOS. Anything that is required by your program should be
listed here.
2.4 - The .MAK file box. If you use a .MAK file with your program, the
files listed in that .MAK file will be listed in that box.
2.5 - The COMMAND LINE PARAMETERS box. If when compiled your program
requires or allows command line parameters, COMMENTS will prompt
you to type in the different parameters that are allowed along
with a short description. You should also write a line describing
the syntax of the command. Everything you will type in when
prompted will be enclosed in this box.
2.6 - The VARIABLES box. This box will contain a list of all the
different variables and arrays that are used in the module level
of your program. Each variable and array is listed on a separate
line so the next time you load your listing in the QuickBASIC
editing environment, you may add a short description for each of
these variables and arrays.
COMMENTS v.1.2 - by LAMCO Software Page 4
┌┬──────────────────────────────────────────────────────────────────────┬┐
││ 3 - What is added to each procedure of your listing ││
└┴──────────────────────────────────────────────────────────────────────┴┘
3.1 - The NAME box which tells the name of the procedure and whether it
is a subprogram or a function.
3.2 - The DESCRIPTION box contains the description of the procedure.
COMMENTS prompts you to type it in whenever a new procedure is
analyzed.
3.3 - The PARAMETERS box. If any variables, arrays, or TYPE structures
are passed to a procedure through parameters, COMMENTS will
identify them and list them in this box, one to a line, so you
may later add a description to each of them.
3.4 - The VARIABLES box. Same as in the module level section but
contains, of course, only the variables and arrays used within
the concerned procedure.
3.5 - Finally, the MODULE LEVEL DECLARATIONS box. This box contains
each declaration that must be made in the module level section of
your listing for the concerned procedure to work properly, except
for DIM statements.
This means that if a TYPE structure is used in the procedure, the TYPE
declaration that is required in the module level will be written in that
box. If a constant is used, a CONST declaration will be written. And a
DECLARE SUB or DECLARE FUNCTION declaration will be written in that box
for each procedure that is called from within the procedure.
If you should eventually copy the procedure to another of your listings,
you can find out immediately by looking at this box what are the
declarations that you must add to the module level of this new listing for
that procedure to work properly. As for the DIM statements, look in the
PARAMETERS and VARIABLES boxes to find the arrays used, and then add the
propper DIM statements in the module level or REDIM statements in the
procedure itself.
Note : All these boxes are added to your listing, whether they are
required or not. For example, if you do not use any variables in a given
procedure, the VARIABLES box for that procedure will contain a single line
saying "(none)". You may remove these unnecessary boxes if you wish, but
they may be useful since looking at the beginning of a procedure tells you
immediately what is in there and what is not.
COMMENTS v.1.2 - by LAMCO Software Page 5
┌┬──────────────────────────────────────────────────────────────────────┬┐
││ 4 - Requirements ││
└┴──────────────────────────────────────────────────────────────────────┴┘
In order for COMMENTS to work properly, your listings must be written in a
certain way, but as you'll see, you probably already follow most of these
conventions.
4.1 - The last line of the module level of your listing must be an
"END" statement alone on one line. If you use more than one "END"
statement, replace all of them except the last one by "SYSTEM",
or use another QuickBASIC statement on the same line.
For example, if you make a test that uses an "END" statement, as
in the following case,
IF Level% = 5 THEN
END
ELSE
Level% = Level% + 1
END IF
You can write the same test in any of the following ways :
4.1.1 - IF Level% = 5 THEN END ELSE Level% = Level% + 1
4.1.2 - IF Level% = 5 THEN
CLS : END
ELSE
Level% = Level% + 1
END IF
4.1.3 - IF Level% = 5 THEN Note : CLS has no effect
END : CLS since the program
ELSE will end before
Level% = Level% + 1 reaching it
END IF
The trick is simply not to write any "END" statement that is not
the last one alone on one line, and whatever is on that line must
not be a remark or a string within doublequotes.
4.2 - All Variables, Arrays, Constants, TYPE Structures, Subprogram
names, Function names, and Parameters as well as COMMAND LINE
Parameters, if any, must contain at least one lowercase letter.
COMMENTS compares each string in your listing with its uppercase
equivalent. This goes much faster than comparing it against every
QuickBASIC reserved word, but requires the use of lowercase
letters.
COMMENTS v.1.2 - by LAMCO Software Page 6
4.3 - If you use TYPE statements, do not write comment lines between
the TYPE and the END TYPE lines.
The following example will generate an error condition :
TYPE SortType
Length AS INTEGER ' Bar length (the element compared
' in the different sorts)
ColorVal AS INTEGER ' Bar color
BarString AS STRING * 43 ' The bar (string of 43 characters)
END TYPE
Rather write this example in the following way :
TYPE SortType
Length AS INTEGER ' Bar length (the element compared
ColorVal AS INTEGER ' Bar color in the diff. sorts)
BarString AS STRING * 43 ' The bar (string of 43 characters)
END TYPE
Or write the comments before or after the TYPE declaration :
TYPE SortType
Length AS INTEGER
ColorVal AS INTEGER
BarString AS STRING * 43
END TYPE
' Length is the Bar legth (the element compared in the
' different sorts)
' ColorVal is the Bar color
' BarString is the Bar (string of 43 chrracters)
4.4 - If you use labels before DATA statements at the beginning of the
module level part of your program, you should write them all in
uppercase. Otherwise, COMMENTS will list them as variables.
On the other hand, if you use labels after the "END" statement in
error-handling routines, you must slightly modify your listing in the
following way :
DO NOT write an "END" statement before the error-handling routines, but
DO write one after the routines. Then run COMMENTS. Afterwards, load
your program into QuickBASIC, remove the "END" statement that is after
the error-handling routines and add an "END" statement before the
routines.
If you don't modify your program in this way, COMMENTS will either
generate an error message and terminate or it won't copy the
error-handling routines in the new version of your listing.
As for everything else, you may write your program in any way that is
acceptable to QuickBASIC.
COMMENTS v.1.2 - by LAMCO Software Page 7
┌┬──────────────────────────────────────────────────────────────────────┬┐
││ 5 - How COMMENTS works ││
└┴──────────────────────────────────────────────────────────────────────┴┘
COMMENTS opens the file you have selected and then reads each line one by
one. Each time a line is read, it is copied to a backup file. Then remarks
and strings within doublequotes are removed from that line. All characters
that are not numbers or letters are removed and each string left is then
analyzed.
Statements such as CONST or DIM tell COMMENTS what the following strings
are. Every important string found is stored in memory and when the whole
file as been read and backed up, the original file is closed and reopened.
The file is then read again, only this time each line is copied to a
temporary file with the same name as your listing but with a .TMP
extension. As the file is read again, each string found that does not
match its uppercase equivalent is compared to the strings in memory and
stored according to what it is. This is why it is important that each
variable, SubProgram name, and so forth, contains at least one lowercase
letter. The other way around would have been to compare each string found
with every QuickBASIC reserved word, which would take much more time.
Once the end of the module level is reached, the .TMP file is closed and a
new file with a .NEW extension is opened. All the module level boxes
containing the appropriate information are written to this file and the
.TMP file that now contains the module level part of your original listing
without any modification is then copied to the .NEW file.
The temporary file is then deleted and a new temporary file is opened.
COMMENTS then reads the lines of the original file until the beginning of
the first procedure. Then each new line read is copied to the temporary
file while the listing is again analyzed.
Once the end of the first procedure is reached, the appropriate
information and the temporary file are added to the .NEW file and this
process is repeated until the whole listing has been analyzed.
Note : Anything that you write in your listing after the "END" statement
or above the "SUB" or "FUNCTION" statement in any procedure won't be
copied to the temporary file and therefore will not appear in the final
file. This allows you to write temporary remarks that you don't want in
the final version of your program. This is also the reason why you should
merge or copy any 'INCLUDE$ file after the "END" statement of the module
level.
COMMENTS v.1.2 - by LAMCO Software Page 8
┌┬──────────────────────────────────────────────────────────────────────┬┐
││ 6 - About '$INCLUDE files and .MAK files ││
└┴──────────────────────────────────────────────────────────────────────┴┘
COMMENTS is intended to be used with programs that use a single module.
You can, however, use it with programs that use an '$INCLUDE file or with
programs that use more than one module.
- If your listing requires an '$INCLUDE file, merge or copy it in your
original listing after the "END" statement of the module level before
saving your listing.
The merged '$INCLUDE file will not appear in the new version of your
listing if you have merged it after the "END" statement. On the other
hand, if you do not merge it, COMMENTS won't be able to identify the
Constants, TYPE structures, and procedures. Therefore, everything will
be listed as variables.
- If you use more than one module, process them one by one. If you use an
'$INCLUDE file, merge it in each module.
┌┬──────────────────────────────────────────────────────────────────────┬┐
││ 7 - How to use COMMENTS ││
└┴──────────────────────────────────────────────────────────────────────┴┘
Write your program as you would usually do, but make sure you follow the
requirements stated earlier in this document.
Don't write any remark you want to be in your program after the "END"
statement of the module level or above the "SUB " or "FUNCTION" statement
of any procedure.
Once your program is completed, save it in ASCII format and exit
QuickBASIC.
Then call COMMENTS from the directory where your program is. If COMMENTS
is in a subdirectory that appears in the PATH statement of your
AUTOEXEC.BAT file, simply type COMMENTS on the command line and press
[ENTER], otherwise, also type the path to the subdirectory where COMMENTS
is.
Select your program from the list of files that appear on screen and
answer each question as you are prompted.
COMMENTS v.1.2 - by LAMCO Software Page 9
┌┬──────────────────────────────────────────────────────────────────────┬┐
││ 8 - How to use COMMENTS - Systems without a hard drive ││
└┴──────────────────────────────────────────────────────────────────────┴┘
Here's how to use COMMENTS if your system does not have a hard drive.
Copy the file COMMENTS.EXE (the actual program file) to one diskette and
copy your listing to a second diskette. If your listing uses a .MAK file,
copy it also to this second diskette.
Insert the diskette that contains your listing in drive A: and insert the
diskette that contains COMMENTS in drive B:. Then type A: and press
[ENTER] to make sure your current drive is drive A:.
Now call COMMENTS from the A: prompt by typing the following command :
A:>B:COMMENTS
All temporary files as well as the new files created by COMMENTS will be
on the diskette that contains your listing.
It is unlikely that you will run into any problem. But if your listing is
huge, it is possible that you run out of disk space while COMMENTS writes
the temporary files or even while making the backup copy of the original
listing.
To prevent this, you may add the following switch when calling COMMENTS :
A>B:COMMENTS /F or A>B:COMMENTS /f
Note : If you use this switch, COMMENTS will NOT make a copy of the
original listing, therefore leaving more space on the diskette. Be
sure though, if you use this switch, that you have a copy of your
original listing on a different diskette.
COMMENTS v.1.2 - by LAMCO Software Page 10
┌┬──────────────────────────────────────────────────────────────────────┬┐
││ 9 - How to use COMMENTS - Answering prompts ││
└┴──────────────────────────────────────────────────────────────────────┴┘
╔════════════════════════════════════════════════════════════════════════╗
║ COMMENTS - Version 1.2 (c) 1991 - by LAMCO Software ║
╚════════════════════════════════════════════════════════════════════════╝
╔══════════════╗ ╔═══════════════════════════════════════════════════════╗
║ ATTRIB .BAS ║ ║ ║
║ BIN2HEX .BAS ║ ║ QuickBASIC comments adding utility ║
║ BIOSCALL.BAS ║ ║ ║
║ BITS .BAS ║ ║ Available to you through the Shareware concept ║
║ BOXES .BAS ║ ║ ║
║ CALENDAR.BAS ║ ║ Please read the accompanying documentation ║
║ DOLLARS .BAS ║ ║ ║
║ DOSCALLS.BAS ║ ╚═══════════════════════════════════════════════════════╝
║ EDIT .BAS ║ ╔═══════════════════════════════════════════════════════╗
║ ERROR .BAS ║ ║ ║
║ FILEINFO.BAS ║ ║ Reading directory - Please wait ... ║
║ GCURSOR .BAS ║ ║ ║
║ HEX2BIN .BAS ║ ║ Please choose the file to add comments to. ║
║ KEYS .BAS ║ ║ ║
║ MOUSSUBS.BAS ║ ║ [HOME] [END] [PgUp] [PgDn] [Up and Down arrows] ║
║ NEWBOXES.BAS ║ ║ ║
║ PARSE .BAS ║ ║ [ENTER] to select - [ESC] to quit ║
║ STRINGS .BAS ║ ║ ║
╚══════════════╝ ╚═══════════════════════════════════════════════════════╝
Shown above is what appears on screen when COMMENTS is loaded. Only the
files with a .BAS extension in the current directory will be listed and
the first one will be highlighted.
If there are no .BAS files in the current directory, COMMENTS will display
an error message and exit.
If there are more than 18 files with a .BAS extension in the current
directory, use the cursor keys ([HOME], [END], [PGUP], [PGDN], [UP], or
[DOWN]) to display the other .BAS files in the current directory.
Once the listing you want to process is highlighted, press [ENTER].
You may exit COMMENTS at this point by pressing [ESC].
For example purposes, let's select BOXES.BAS and walk through COMMENTS to
show you how it works. Note that for your convenience, both versions of
BOXES.BAS are included with COMMENTS. This listing is not copyrighted and
you are free to use it in your listings. BOXES.BAS is a toolbox that was
written to draw different kinds of boxes on screen in different listings.
BOXES.BAK is the original listing while BOXES.BAS is the new file written
by COMMENTS. The descriptions that appear in the PARAMETERS and VARIABLES
boxes were added after, not by COMMENTS.
COMMENTS v.1.2 - by LAMCO Software Page 11
Once you have highlighted BOXES.BAS and pressed [ENTER], the following
screen will appear :
╔════════════════════════════════════════════════════════════════════════╗
║ COMMENTS - Version 1.2 (c) 1991 - by LAMCO Software ║
╚════════════════════════════════════════════════════════════════════════╝
╔═════════════════════════════╗ ╔═══════════════════════════════════════╗
║ Making backup copy of ║ ║ Number of declared SubPrograms : 7 ║
║ ║ ║ ║
║ BOXES.BAS ║ ║ Number of declared Functions : 0 ║
║ ║ ║ ║
║ while reading it. ║ ║ Number of CONST statements : 0 ║
║ ║ ║ ║
║ Backup filename is ║ ║ Number of TYPE structures : 0 ║
║ ║ ║ ║
║ BOXES.BAK ║ ║ Number of SubPrograms found : 7 ║
║ ║ ║ ║
║ Please wait ... ║ ║ Number of Functions found : 0 ║
║ ║ ║ ║
║ ║ ║ Command line parameters ? : No ║
║ ║ ║ ║
║ ║ ║ .MAK file required ? : No ║
║ ║ ║ ║
║ ║ ║ ║
║ ║ ║ ║
╚═════════════════════════════╝ ╚═══════════════════════════════════════╝
At the beginning, all numbers are set to 0 and the "Command line
parameters ?" and ".MAK file required ?" lines are not displayed. Each
time an important information is found, the corresponding number is
updated and when the whole file has been analyzed, the "Command line
parameters ?" and ".MAK file required ?" lines will be printed with the
appropriate "Yes" or "No".
You will then be prompted to press a key to continue.
COMMENTS v.1.2 - by LAMCO Software Page 12
╔════════════════════════════════════════════════════════════════════════╗
║ COMMENTS - Version 1.2 (c) 1991 - by LAMCO Software ║
╚════════════════════════════════════════════════════════════════════════╝
╔════════════════════════════════════════════════════════════════════════╗
║ Enter name of program : ║
║ ║
║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║
║ ║
║ ║
║ ║
║ ║
║ ║
║ ║
║ ║
║ ║
║ ║
║ ║
║ ║
║ ║
║ ║
║ ║
║ ║
╚════════════════════════════════════════════════════════════════════════╝
The above screen will then appear, with COMMENTS prompting you to enter
the name of your program.
Type the name of your listing in the highlighted box.
Until you press [ENTER], [Up Arrow], or [Down Arrow], COMMENTS gives you
WordStar-like editing capabilities. That is, you can use [INS] to toggle
overwrite mode on and off, [HOME], [END], to move the cursor to the
beginning or the end of the line, Ctrl-Left or Ctrl-Right to move the
cursor to the previous or next word, Ctrl-Q to erase the whole line, or
Ctrl-Q and then Y to erase the end of the line from the cursor position.
COMMENTS v.1.2 - by LAMCO Software Page 13
╔════════════════════════════════════════════════════════════════════════╗
║ COMMENTS - Version 1.2 (c) 1991 - by LAMCO Software ║
╚════════════════════════════════════════════════════════════════════════╝
╔════════════════════════════════════════════════════════════════════════╗
║ Enter name of program : ║
║ ║
║ BOXES ║
║ ║
║ ║
║ Select the Type of the program ╔═════════════╗ ║
║ ║ Application ║ ║
║ [Up and Down arrows] - Move cursor ║ Utility ║ ║
║ ║ Toolbox ║ ║
║ [ENTER] - Select ║ Demo ║ ║
║ ║ Game ║ ║
║ Enter type : ░░░░░░░░░░░░░░░░░░░░░░░ ║ Other ║ ║
║ ╚═════════════╝ ║
║ ║
║ ║
║ ║
║ ║
║ ║
╚════════════════════════════════════════════════════════════════════════╝
Once you have pressed [ENTER], [Up Arrow], or [Down Arrow], the screen
will be modified in the way shown above except for the "Enter type :" line
and highlighted box. This appears only if you select "Other".
You can now select the type of your program by highlighting the
appropriate description, using the [Up] or [Down] arrow. If the type of
your program does not appear in the list, select "Other".
If you do select "Other", you again have access to WordStar-like editing
capabilities until you press [ENTER], [Up Arrow], or [Down Arrow].
COMMENTS v.1.2 - by LAMCO Software Page 14
╔════════════════════════════════════════════════════════════════════════╗
║ COMMENTS - Version 1.2 (c) 1991 - by LAMCO Software ║
╚════════════════════════════════════════════════════════════════════════╝
╔════════════════════════════════════════════════════════════════════════╗
║ Enter name of program : ║
║ ║
║ BOXES ║
║ ║
║ ║
║ Select the Type of the program ╔═════════════╗ ║
║ ║ Application ║ ║
║ [Up and Down arrows] - Move cursor ║ Utility ║ ║
║ ║ Toolbox ║ ║
║ [ENTER] - Select ║ Demo ║ ║
║ ║ Game ║ ║
║ ║ Other ║ ║
║ ╚═════════════╝ ║
║ ║
║ Enter source of program : ║
║ ║
║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║
║ ║
╚════════════════════════════════════════════════════════════════════════╝
The next step is to type in the source of your program. In most cases, it
is your name that you will type there but if the listing comes from a
magazine or a book, or any other source, write the reference here.
Remember the WordStar-like editing capabilities. They apply here as well.
COMMENTS v.1.2 - by LAMCO Software Page 15
╔════════════════════════════════════════════════════════════════════════╗
║ COMMENTS - Version 1.2 (c) 1991 - by LAMCO Software ║
╚════════════════════════════════════════════════════════════════════════╝
╔════════════════════════════════════════════════════════════════════════╗
║ Enter description of program ║
║ ║
║ ║
║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║
║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║
║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║
║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║
║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║
║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║
║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║
║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║
║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║
║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║
║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║
║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║
║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║
║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║
║ ║
╚════════════════════════════════════════════════════════════════════════╝
Once you have entered the source of your listing, COMMENTS will prompt you
for its description. The above screen will appear and you will again have
access to editing capabilities.
In this case, though, [ENTER], [Up Arrow], and [Down Arrow] move the
cursor up or down one line. You must press [ESC] to exit from this
highlighted box. Don't worry about exceeding the length of the lines,
COMMENTS provides wrap-around capabilities.
Note, however, that when you exit this box, COMMENTS will concatenate
everything you have written into one line and will then break that line in
as many lines as required to fit the text into the comment box that will
be added to your listing, removing any double spaces in the process.
Therefore, you may not include blank lines within the box while using
COMMENTS, but you may do so when you later load the new version of your
listing in QuickBASIC.
If you want to see what the text will look like in its final version, move
the cursor to the upper left corner of the highlighted box and press the
[BACKSPACE] key.
COMMENTS v.1.2 - by LAMCO Software Page 16
╔════════════════════════════════════════════════════════════════════════╗
║ COMMENTS - Version 1.2 (c) 1991 - by LAMCO Software ║
╚════════════════════════════════════════════════════════════════════════╝
╔══════════════════════════════════════════════╗ ╔═══════════════════════╗
║ Select the Requirements of the program ║ ║ (none) ║
║ ║ ║ DOS 2.x ║
║ [Up and Down arrows] - Move cursor ║ ║ DOS 3.x ║
║ ║ ║ DOS 4.x ║
║ [ENTER] - Select/Unselect ║ ║ CGA ║
║ ║ ║ EGA ║
║ [ESC] - Exit ║ ║ VGA or MCGA ║
║ ║ ║ Mouse ║
║ ║ ║ Mouse (optional) ║
╚══════════════════════════════════════════════╝ ║ Modem ║
╔══════════════════════════════════════════════╗ ║ Joystick ║
║ ║ ║ Printer ║
║ ║ ║ Other ║
║ ║ ║ Other ║
║ ║ ║ Other ║
║ ║ ║ Other ║
║ ║ ║ Other ║
║ ║ ║ Other ║
╚══════════════════════════════════════════════╝ ╚═══════════════════════╝
There are still two more things that only you can tell COMMENTS, the
requirements of your program and the language you used to write it. But
both are simple to do.
Shown above is the screen that prompts you for the requirements of your
program. Use the [Up] and [Down] arrows to select each of the requirements
that apply to your program. When all the requirements have been selected,
press [ESC] to exit.
Every time you press [ENTER], the current selection that is highlighted
will be marked. You remove a mark by pressing [ENTER] while highlighting a
selection that is already marked. When you press [ESC], all requirements
marked will be included in the requirements box added to your listing.
If you need a requirement that is not written as an available selection,
select any of the "Other" lines. COMMENTS will prompt you to type that
requirement. Again, you have access to editing capabilities until you
press [ENTER], [Up], or [Down] arrow. Should you notice too late that
you've made a typing mistake, highlight the requirement line that contains
the misspelled word, unselect it by pressing [ENTER], highlight another
"Other" line, and type a new line.
The "Other" lines are provided so you can add such remarks as '$INCLUDE
files, special libraries, or anything else that is required by your
program to work properly.
COMMENTS v.1.2 - by LAMCO Software Page 17
Now, the language you used to write your program. Use the [Up] and [Down]
arrows to highlight the version of QuickBASIC that you used or select
"Other" if you used another BASIC language and press [ENTER].
╔════════════════════════════════════════════════════════════════════════╗
║ COMMENTS - Version 1.2 (c) 1991 - by LAMCO Software ║
╚════════════════════════════════════════════════════════════════════════╝
╔══════════════════════════════════════════════╗ ╔═══════════════════════╗
║ Select the Requirements of the program ║ ║ (none) ║
║ ║ ║ DOS 2.x ║
║ [Up and Down arrows] - Move cursor ║ ║ DOS 3.x ║
║ ║ ║ DOS 4.x ║
║ [ENTER] - Select/Unselect ║ ║ √ CGA ║
║ ║ ║ EGA ║
║ [ESC] - Exit ║ ║ VGA or MCGA ║
║ ║ ║ Mouse ║
║ ║ ║ Mouse (optional) ║
╚══════════════════════════════════════════════╝ ║ Modem ║
╔══════════════════════════════════════════════╗ ║ Joystick ║
║ Select language used in the program ║ ║ Printer ║
║ ║ ║ Other ║
║ QuickBASIC V. 4.0 ║ ║ Other ║
║ QuickBASIC V. 4.5 ║ ║ Other ║
║ Other ║ ║ Other ║
║ ║ ║ Other ║
║ ║ ║ Other ║
╚══════════════════════════════════════════════╝ ╚═══════════════════════╝
If your program uses Command Line Parameters, another screen will be
displayed and COMMENTS will prompt you to enter the appropriate
information.
To allow you to write each parameter on a different line, the editing
capabilities inside this box are the same as when editing only one line.
Each time you press [ENTER], [Up], or [Down] arrow, the cursor moves to
the next line and you can no longer edit the previous line.
To exit from that box, press [ENTER], [Up] or [Down] arrow on a blank
line.
COMMENTS v.1.2 - by LAMCO Software Page 18
╔════════════════════════════════════════════════════════════════════════╗
║ COMMENTS - Version 1.2 (c) 1991 - by LAMCO Software ║
╚════════════════════════════════════════════════════════════════════════╝
╔════════════════════════════════════════════════════════════════════════╗
║ Now processing : Module level ║
║ ║
║ Variables found : 0 Reading ║
╚════════════════════════════════════════════════════════════════════════╝
╔════════════════════════════════════════════════════════════════════════╗
║ ║
║ ║
║ ║
║ ║
║ ║
║ ║
║ ║
║ ║
║ ║
║ ║
║ ║
║ ║
║ ║
╚════════════════════════════════════════════════════════════════════════╝
Once all the necessary information has been entered, the next screen to
appear will be as shown above.
COMMENTS is now analyzing the module level section of the program. Each
time a new variable (or array) is found, the appropriate number is
displayed. When the "END" statement is reached, "Reading" is replaced by
"Writing". COMMENTS then writes the appropriate boxes to the .NEW file and
copies the temporary file after the boxes.
Note : All the screens that are shown in this manual are actual screens
that were saved when the original BOXES.BAS was processed through
COMMENTS. If you rename BOXES.BAK and give it a .BAS extension, you can
process that listing through COMMENTS and follow the screens as COMMENTS
processes that newly named version of BOXES. You should print a copy of
BOXES.BAK and BOXES.BAS before you do so. This will allow you to easily
understand what is going on while COMMENTS is working, as well as provide
you with the description you should type in when prompted.
COMMENTS v.1.2 - by LAMCO Software Page 19
╔════════════════════════════════════════════════════════════════════════╗
║ COMMENTS - Version 1.2 (c) 1991 - by LAMCO Software ║
╚════════════════════════════════════════════════════════════════════════╝
╔════════════════════════════════════════════════════════════════════════╗
║ Now processing : SUBPROGRAM DoubleBorderBox ║
║ ║
║ Variables found : 1 Procedure # 1 of 7 Reading ║
╚════════════════════════════════════════════════════════════════════════╝
╔════════════════════════════════════════════════════════════════════════╗
║ ║
║ ║
║ ║
║ ║
║ ║
║ ║
║ ║
║ ║
║ ║
║ ║
║ ║
║ ║
║ ║
╚════════════════════════════════════════════════════════════════════════╝
COMMENTS then resumes reading the file and when it finds the first
procedure, it will replace "Module level" by either "SUBPROGRAM" or
"FUNCTION" and will display the name of the procedure it is reading. Again
the number of variables found is shown. COMMENTS also tells how many
procedures it will have to process and which is the one that is currently
being read.
When COMMENTS finds an "END SUB" or "END FUNCTION" statement, actually the
end of the procedure it was reading, a message and a highlighted box will
appear on screen and COMMENTS will prompt you for the description of that
procedure. Once you've typed it, COMMENTS will resume its reading.
COMMENTS v.1.2 - by LAMCO Software Page 20
╔════════════════════════════════════════════════════════════════════════╗
║ COMMENTS - Version 1.2 (c) 1991 - by LAMCO Software ║
╚════════════════════════════════════════════════════════════════════════╝
╔════════════════════════════════════════════════════════════════════════╗
║ Now processing : SUBPROGRAM DoubleBorderBox ║
║ ║
║ Variables found : 1 Procedure # 1 of 7 Writing ║
╚════════════════════════════════════════════════════════════════════════╝
╔════════════════════════════════════════════════════════════════════════╗
║ Enter description of procedure ║
║ ║
║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║
║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║
║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║
║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║
║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║
║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║
║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║
║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║
║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║
║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║
║ ║
╚════════════════════════════════════════════════════════════════════════╝
When prompted to type the description of a procedure, the editing
capabilities are the same as when entering the description of the program
itself. Exit by pressing [ESC]. When the last procedure has been
processed, the original .BAS file will be deleted (Remember that a copy
with a .BAK extension was made when the file was read the first time) and
the .NEW file is renamed with a .BAS extension.
COMMENTS will then display a message telling that it is writting the
structure file and when this is completed, it will display another message
telling you that the processing of your listing is completed and prompting
you to press a key to exit the program.
When your computer is back to the command line, you should load
QuickBASIC, call your program and then add remarks in the overstrike mode
for each of the variables and parameters that COMMENTS has identified in
your program.
If you wish, you may merge the structure file to the main module of your
program since each line begins with an apostrophe and the whole file is
written in the same format as the other information that was added to your
listing.
Note that you can use COMMENTS before the final version of your program is
completed. This might prove useful to find where there is a misspelled
variable since both versions of that variable will be added to your
listing in the variables list. Remember though that COMMENTS will write
new boxes when you run it again on the new listing with a .BAS extension.
If you use COMMENTS on a version of your program that is not the final
one, delete the .BAS file after you've looked at it and rename the .BAK
file with a .BAS extension so you use again your original listing.
COMMENTS v.1.2 - by LAMCO Software Page 21
┌┬──────────────────────────────────────────────────────────────────────┬┐
││ 10 - COMMENTS Limitations ││
└┴──────────────────────────────────────────────────────────────────────┴┘
COMMENTS will display an error message and terminate if your listing
exceeds these limits :
100 files with a .BAS extension in the current directory
25 files in a .MAK file
60 Constants
25 TYPE structures
40 variables in any TYPE structure
100 Subprograms
60 Functions
100 different arrays in the whole listing
100 variables and arrays used within any procedure
COMMENTS will also terminate if there is no "END" statement at the end of
the module level section of your listing.
Note : When COMMENTS terminates because of a problem, it doesn't erase any
file. Therefore you may find a ".BAK", ".TMP", or ".NEW" file in
your directory. These files need not be deleted since COMMENTS will
overwrite them the next time you use it for the same listing.
Also note that the original file is renamed only when the whole process is
completed. So should COMMENTS stop because of any problem, DO NOT erase
the ".BAS" file and rename the ".BAK" file. The ".BAS" file is your
original listing. The ".BAK" file is a copy of it, but if COMMENTS stopped
before it had time to copy all the lines of your original listing, the
".BAK" file is not complete.
If a problem occurs, note the error message and look at the ".BAK",
".TMP", and ".NEW" files. You will then easily find out why COMMENTS
stopped.
If your computer has less than 640K of RAM (Random Access Memory), the
limitations mentionned above may actually be smaller than stated.
COMMENTS v.1.2 - by LAMCO Software Page 22
┌┬──────────────────────────────────────────────────────────────────────┬┐
││ 11 - Technical support ││
└┴──────────────────────────────────────────────────────────────────────┴┘
COMMENTS has been tested extensively, and has worked fine with all the
listings I have ran through it, as long as the listing respected the
requirements described in sections 4 and 9 of this documentation.
Should you, however, run into any problem, please write to me. Most of
the programs I write are in QuickBASIC and I run all my listings through
COMMENTS. Therefore, I will definitely upgrade it, since I would like
it to process the multiple modules listings I write. Time here, is the
only problem, the source code file, striped of all comments and blank
lines is pretty close to the 64K barrier. The next upgrade means that I
must first break the code into at least two or three modules.
You can write to me at one of the following addresses :
In U.S.A. : In Canada :
LAMCO Software LAMCO Software
P.O. Box 847 P.O. Box 46
St-Albans Postal Station P.A.T.
VT Montreal, Quebec
05478 H1B 5K1
Please note that I am a Canadian. Mail that is sent to me in my
canadian P.O. Box is checked and answered on a daily basis. The mail
that is sent to my U.S. P.O. Box is picked up every monday morning
and answered on the same day, so you may expect a slight delay if you
address your mail to my U.S. P.O. Box.
┌┬──────────────────────────────────────────────────────────────────────┬┐
││ 12 - What's coming up in version 2.0 ││
└┴──────────────────────────────────────────────────────────────────────┴┘
When a .MAK file is used, version 2.0 will be able to process all the
modules and read the '$INCLUDE files. The structure file will also
indicate in which module is each procedure called.
Comments added to your listing will be updated rather than overwritten, so
you won't have to type in the same information twice or more if you run
COMMENTS more than once on the same listing.
Version 2.0 will also include configuration possibilities, so you can set
the colors and type in only once options that you use often in your
listings, such as Requirements, Source, or Language.
COMMENTS v.1.2 - by LAMCO Software Page 23
┌┬──────────────────────────────────────────────────────────────────────┬┐
││ 13 - About Shareware ││
└┴──────────────────────────────────────────────────────────────────────┴┘
COMMENTS is distributed through the Shareware concept. You are therefore
encouraged to make copies and give them to anyone who might use it. We
would also greatly appreciate it if you help us make it available to more
users by uploading it to any BBS you have access to.
The registration fee for COMMENTS is $ 20.00 (US$). Anyone who sends
$ 30.00 or more will receive Version 2 as soon as it is available.
Please support the Shareware concept. If you use COMMENTS, send your
registration to one of the following addresses :
In U.S.A. : In Canada :
LAMCO Software LAMCO Software
P.O. Box 847 P.O. Box 46
St-Albans Postal Station P.A.T.
VT Montreal, Quebec
05478 H1B 5K1
Please use the file REGISTER.FRM that accompanies this package.
When you register, you will receive a printed manual, the latest
registered version of the program and the source code of a few toolboxes
you may use in your listings. The registered version of the program is the
same as the Shareware version but does not have the beginning screen. When
you use the program you get directly to the list of the .BAS files.
Help us make a better product available to you. Send us your suggestions
and please report any problem.
COMMENTS was written with QuickBASIC version 4.5 and is intended to be
used with either version 4.0 or 4.5 of QuickBASIC, but you may use it with
other versions of QuickBASIC or other BASIC languages, as long as your
listing was saved in ASCII format.
If you use COMMENTS with another BASIC language and you find that COMMENTS
doesn't work properly, please write to us, describing what happened. Maybe
we can modify COMMENTS so Version 2 will accept the other BASIC languages
as well or at least tell you how you could write your program so COMMENTS
will work.
COMMENTS v.1.2 - by LAMCO Software Page 24
